home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Dev / Bgui / AutoDoc / commodityclass.doc < prev    next >
Encoding:
Text File  |  2000-05-09  |  9.5 KB  |  490 lines
  1. TABLE OF CONTENTS
  2.  
  3. commodityclass/--background--
  4. commodityclass/CM_ADDHOTKEY
  5. commodityclass/CM_DISABLEBROKER
  6. commodityclass/CM_DISABLEHOTKEY
  7. commodityclass/CM_ENABLEBROKER
  8. commodityclass/CM_ENABLEHOTKEY
  9. commodityclass/CM_MSGINFO
  10. commodityclass/CM_REMHOTKEY
  11. commodityclass/COMM_Description
  12. commodityclass/COMM_ErrorCode
  13. commodityclass/COMM_Name
  14. commodityclass/COMM_Notify
  15. commodityclass/COMM_Priority
  16. commodityclass/COMM_ShowHide
  17. commodityclass/COMM_SigMask
  18. commodityclass/COMM_Title
  19. commodityclass/COMM_Unique
  20.  
  21. commodityclass/--background--
  22.  
  23.     NAME
  24.     Class:        commodityclass
  25.     Superclass:    ROOTCLASS
  26.     Include File:    <bgui/bgui_cx.h>
  27.  
  28.     FUNCTION
  29.     To  provide  a    BOOPSI based interface to the commodities.library.
  30.     This  class  will allow you to setup and maintain a simple broker with
  31.     simple hotkeys.  The attached hotkeys can also be disabled  separately
  32.     and enabled.
  33.  
  34. commodityclass/CM_ADDHOTKEY
  35.  
  36.     NAME
  37.     CM_ADDHOTKEY -- Add a hotkey to the broker.
  38.  
  39.     SYNOPSIS
  40.     err = DoMethod( obj, CM_ADDHOTKEY, desc, id, flags );
  41.  
  42.     ULONG        err;
  43.     STRPTR        desc;
  44.     ULONG        id;
  45.     ULONG        flags;
  46.  
  47.     FUNCTION
  48.     This  method  must  be    used  to  attach  hotkeys  to the broker.  The
  49.     hotkey is defined with an input description string just like that used
  50.     by the amiga.lib HotKey() function.
  51.  
  52.     INPUTS
  53.     desc    - This    must  point  to  a  string  in    which  the  hotkey  is
  54.         described.  The input description string is the same string as
  55.         you  would pass the HotKey()  routine  from the amiga.lib link
  56.         library.
  57.  
  58.     id    - This    must be an  integer  which  represents    the  ID of the
  59.         key.  This  must  be a unique value as this ID will be used to
  60.         identify the key. Please note  that  you  should  keep    the ID
  61.         between 1 and 65535 (I.E. In  the  lower  16 bits.) if you use
  62.         the V40 style of message handling.
  63.  
  64.     flags    - This    field  may have  any of the following flags set:
  65.  
  66.         CAHF_DISABLED - When set the key is added to the broker but it
  67.             is disabled from usage.
  68.  
  69.     RESULT
  70.     err    - TRUE for success, FALSE for failure.    When FALSE is returned
  71.         you can use the COMM_ErrorCode attribute to find  out  what it
  72.         was that failed.
  73.  
  74.     EXAMPLE
  75.     Object    *broker;
  76.     #define ID_SF1        1
  77.  
  78.     /*
  79.      *    Add shift+f1 as a hotkey to the
  80.      *    broker object.
  81.      */
  82.     DoMethod( broker, CM_ADDHOTKEY, "shift f1", ID_SF1, 0L );
  83.  
  84.     SEE ALSO
  85.     CM_REMHOTKEY, CM_MSGINFO, COMM_ErrorCode, amiga.lib/HotKey()
  86.  
  87. commodityclass/CM_DISABLEBROKER
  88.  
  89.     NAME
  90.     CM_DISABLEBROKER -- Disable the commodity broker.
  91.  
  92.     SYNOPSIS
  93.     DoMethod( obj, CM_DISABLEBROKER );
  94.  
  95.     FUNCTION
  96.     To disable the commodity broker.
  97.  
  98.     INPUTS
  99.  
  100.     RESULT
  101.  
  102.     EXAMPLE
  103.     Object        *broker;
  104.  
  105.     /*
  106.      *    Disable commodity broker.
  107.      */
  108.     DoMethod( broker, CM_DISABLEBROKER );
  109.  
  110.    SEE ALSO
  111.     CM_ENABLEBROKER
  112.  
  113. commodityclass/CM_DISABLEHOTKEY
  114.  
  115.     NAME
  116.     CM_DISABLEHOTKEY -- Disable a hotkey.
  117.  
  118.     SYNOPSIS
  119.     err = DoMethod( obj, CM_DISABLEHOTKEY, id );
  120.  
  121.     ULONG        err;
  122.     ULONG        id;
  123.  
  124.     FUNCTION
  125.     To disable a hotkey. It is not necessary to disable the  broker  to do
  126.     this. This method will take care of this for you.
  127.  
  128.     INPUTS
  129.     id    - The ID of the key to disable.
  130.  
  131.     RESULT
  132.     err    - True for succes, FALSE for failure.
  133.  
  134.     EXAMPLE
  135.     Object        *broker;
  136.     #define         ID_SF1        1
  137.  
  138.     /*
  139.      *    Disable the hotkey with this ID.
  140.      */
  141.     DoMethod( broker, CM_DISABLEHOTKEY, ID_SF1 );
  142.  
  143.     SEE ALSO
  144.     CM_ENABLEHOTKEY
  145.  
  146. commodityclass/CM_ENABLEBROKER
  147.  
  148.     NAME
  149.     CM_ENABLEBROKER -- Enable the commodity broker.
  150.  
  151.     SYNOPSIS
  152.     DoMethod( obj, CM_ENABLEBROKER );
  153.  
  154.     FUNCTION
  155.     To enable the commodity broker.
  156.  
  157.     INPUTS
  158.  
  159.     RESULT
  160.  
  161.     EXAMPLE
  162.     Object        *broker;
  163.  
  164.     /*
  165.      *    Enable commodity broker.
  166.      */
  167.     DoMethod( broker, CM_ENABLEBROKER );
  168.  
  169.    SEE ALSO
  170.     CM_DISABLEBROKER
  171.  
  172. commodityclass/CM_ENABLEHOTKEY
  173.  
  174.     NAME
  175.     CM_ENABLEHOTKEY -- Enable a hotkey.
  176.  
  177.     SYNOPSIS
  178.     err = DoMethod( obj, CM_ENABLEHOTKEY, id );
  179.  
  180.     ULONG        err;
  181.     ULONG        id;
  182.  
  183.     FUNCTION
  184.     To enable a hotkey. It is not necessary to disable the    broker    to  do
  185.     this. This method will take care of this for you.
  186.  
  187.     INPUTS
  188.     id    - The ID of the key to enable.
  189.  
  190.     RESULT
  191.     err    - True for success, FALSE for failure.
  192.  
  193.     EXAMPLE
  194.     Object        *broker;
  195.     #define         ID_SF1        1
  196.  
  197.     /*
  198.      *    Enable the hotkey with this ID.
  199.      */
  200.     DoMethod( broker, CM_ENABLEHOTKEY, ID_SF1 );
  201.  
  202.     SEE ALSO
  203.     CM_DISABLEHOTKEY
  204.  
  205. commodityclass/CM_MSGINFO
  206.  
  207.     NAME
  208.     CM_MSGINFO -- Examine commodity broker messages.
  209.  
  210.     SYNOPSIS
  211.     cont = DoMethod( obj, CM_MSGINFO, type, id, data );
  212.  
  213.     ULONG         cont;
  214.     ULONG        *type;
  215.     ULONG        *id;
  216.     ULONG        *data;
  217.  
  218.     FUNCTION
  219.     To get the pending commodity messages and extract  the    necessary data
  220.     from them. You supply storage space for the data you need to know.
  221.  
  222.     INPUTS
  223.     type    - When non-NULL the  result of    CxMsgType()  on the  commodity
  224.         message is stored here.
  225.  
  226.     id    - When non-NULL  the  result of  CxMsgID()  on    the  commodity
  227.         message is stored here.
  228.  
  229.     data    - When non-NULL the  result of    CxMsgData()  on the  commodity
  230.         message is stored here.
  231.  
  232.     RESULT
  233.     CMMI_NOMORE  when  all    messages  have been processed.     You must keep
  234.     calling this method until CMMI_NOMORE is returned.
  235.  
  236.     Since V40 the class can also return any of the following return codes:
  237.  
  238.         CMMI_KILL -- Uppon  receiving  this  return  code  you    should
  239.             remove yourself from the system and terminate.
  240.  
  241.         CMMI_DISABLE -- This return code tell's you that the broker is
  242.             disabled. At the time you get this message  the broker
  243.             has already been disabled.
  244.  
  245.         CMMI_ENABLE -- When this is returned the broker is enabled. At
  246.             the time you get this message the broker  has  already
  247.             been enabled.
  248.  
  249.         CMMI_UNIQUE -- When  this  is  returned  another commodity has
  250.             been  attemted    to  run  using your broker name.   You
  251.             should let the user know this happened. Usually you do
  252.             this by popping up your GUI.
  253.  
  254.         CMMI_APPEAR -- This is returned when you are requested to open
  255.             up the GUI of the commodity.
  256.  
  257.         CMMI_DISAPPEAR -- This will be returned when you are requested
  258.             to close down the GUI of the commodity.
  259.  
  260.     Any return code other than these is the  ID of    a  CXM_IEVENT message.
  261.     This normally is the ID of an attached hotkey.
  262.  
  263.     EXAMPLE:
  264.     Object        *com_obj;
  265.     ULONG         mask = 0, type, id, data, rc;
  266.     BOOL         running = TRUE;
  267.  
  268.     GetAttr( COMM_SigMask, com_obj, &mask );
  269.  
  270.     do {
  271.         Wait( mask );
  272.         while (( rc = DoMethod( com_obj,
  273.                     CM_MSGINFO,
  274.                     &type,
  275.                     &id,
  276.                     &data )) != CMMI_NOMORE ) {
  277.             switch ( type ) {
  278.                 ...
  279.             }
  280.         }
  281.     } while ( running );
  282.  
  283.     /* Or (V40 style) */
  284.  
  285.     do {
  286.         Wait( mask );
  287.         while (( rc = DoMethod( com_obj,
  288.                     CM_MSGINFO,
  289.                     NULL,
  290.                     NULL,
  291.                     NULL )) != CMMI_NOMORE ) {
  292.             switch ( rc ) {
  293.                 ...
  294.             }
  295.         }
  296.     } while ( running );
  297.  
  298.     SEE ALSO
  299.     CM_ADDHOTKEY
  300.  
  301. commodityclass/CM_REMHOTKEY
  302.  
  303.     NAME
  304.     CM_REMHOTKEY -- Remove a hotkey from the broker.
  305.  
  306.     SYNOPSIS
  307.     err = DoMethod( obj, CM_REMHOTKEY, id );
  308.  
  309.     ULONG        err;
  310.     ULONG        id;
  311.  
  312.     FUNCTION
  313.     To remove a hotkey previously added with CM_ADDHOTKEY from the broker.
  314.     It is not necessary to disable the key or the broker to do this.  This
  315.     method will take care of this for you.
  316.  
  317.     INPUTS
  318.     id    - The ID of the key to remove.
  319.  
  320.     RESULT
  321.     err    - True for succes, FALSE for failure.
  322.  
  323.     EXAMPLE
  324.     Object        *broker;
  325.     #define         ID_SF1        1
  326.  
  327.     /*
  328.      *    Remove the hotkey with this
  329.      *    ID from the broker.
  330.      */
  331.     DoMethod( broker, CM_REMHOTKEY, ID_SF1 );
  332.  
  333.     SEE ALSO
  334.     CM_ADDHOTKEY
  335.  
  336. commodityclass/COMM_Description
  337.  
  338.     NAME
  339.     COMM_Description -- ( STRPTR )
  340.  
  341.     FUNCTION
  342.     To specify a short description of the commodity functionality.
  343.  
  344.     DEFAULT
  345.     NULL.
  346.  
  347.     APPLICABILITY
  348.     (I).
  349.  
  350. commodityclass/COMM_ErrorCode
  351.  
  352.     NAME
  353.     COMM_ErrorCode -- ( ULONG )
  354.  
  355.     FUNCTION
  356.     To find out exactly what went wrong when adding a hotkey to the broker
  357.     failed.  Getting  this    attribute  can    result    in the following error
  358.     codes:
  359.  
  360.     CMERR_OK -- OK. No problems.
  361.     CMERR_NO_MEMORY -- Out of memory.
  362.     CMERR_KEYID_IN_USE -- Key ID was already used.
  363.     CMERR_KEY_CREATION -- Key creation failed.
  364.     CMERR_CXOBJERROR -- CxObjError() reported failure.
  365.  
  366.     APPLICABILITY
  367.     (G).
  368.  
  369.     SEE ALSO
  370.     CM_ADDHOTKEY
  371.  
  372. commodityclass/COMM_Name
  373.  
  374.     NAME
  375.     COMM_Name -- ( STRPTR )
  376.  
  377.     FUNCTION
  378.     To specify the name the commodity will have.
  379.  
  380.     DEFAULT
  381.     NULL.
  382.  
  383.     APPLICABILITY
  384.     (I).
  385.  
  386. commodityclass/COMM_Notify
  387.  
  388.     NAME
  389.     COMM_Notify -- ( BOOL )
  390.  
  391.     FUNCTION
  392.     When set to TRUE your  broker  will  be  notified  when  it  has  been
  393.     attempted to run a commodity with the same name.
  394.  
  395.     DEFAULT
  396.     TRUE.
  397.  
  398.     APPLICABILITY
  399.     (I).
  400.  
  401.     SEE ALSO
  402.     COMM_Unique
  403.  
  404. commodityclass/COMM_Priority
  405.  
  406.     NAME
  407.     COMM_Priority -- ( BYTE )
  408.  
  409.     FUNCTION
  410.     To specify the priority of the commodity (not the task priority, but
  411.     the value of the CX_PRIORITY tooltype)
  412.  
  413.     DEFAULT
  414.     0.
  415.  
  416.     APPLICABILITY
  417.     (I).
  418.  
  419. commodityclass/COMM_ShowHide
  420.  
  421.     NAME
  422.     COMM_ShowHide -- ( BOOL )
  423.  
  424.     FUNCTION
  425.     When set to TRUE your broker will get notified when it is supposed  to
  426.     open or close it's window(s).
  427.  
  428.     DEFAULT
  429.     FALSE.
  430.  
  431.     APPLICABILITY
  432.     (I).
  433.  
  434. commodityclass/COMM_SigMask
  435.  
  436.     NAME
  437.     COMM_SigMask -- ( ULONG )
  438.  
  439.     FUNCTION
  440.     To obtain the broker signal  mask  which  can  be  used  to  wait  for
  441.     commodity events to occur.
  442.  
  443.     EXAMPLE
  444.  
  445.     Object           *CO_Com;
  446.     ULONG        mask, sigrec;
  447.  
  448.     GetAttr( COMM_SigMask, CO_Com, &mask );
  449.  
  450.     do {
  451.         sigrec = Wait( mask );
  452.         ...
  453.     } while ( ... );
  454.  
  455.     APPLICABILITY
  456.     (G).
  457.  
  458. commodityclass/COMM_Title
  459.  
  460.     NAME
  461.     COMM_Title -- ( STRPTR )
  462.  
  463.     FUNCTION
  464.     To specify the title of the commodity.
  465.  
  466.     DEFAULT
  467.     NULL.
  468.  
  469.     APPLICABILITY
  470.     (I).
  471.  
  472. commodityclass/COMM_Unique
  473.  
  474.     NAME
  475.     COMM_Unique -- ( BOOL )
  476.  
  477.     FUNCTION
  478.     When set to TRUE it will not be possible to run commodities  with  the
  479.     same name as this one.
  480.  
  481.     DEFAULT
  482.     TRUE.
  483.  
  484.     APPLICABILITY
  485.     (I).
  486.  
  487.     SEE ALSO
  488.     COMM_Name, COMM_Notify
  489.  
  490.